home *** CD-ROM | disk | FTP | other *** search
/ CD-ROM Today - The Disc! 5 / CD-ROM Today - The Disc (Issue 5)(November 1994).ISO / mac / Mac shareware / Education / RLaB / help / getline < prev    next >
Text File  |  1994-09-21  |  2KB  |  82 lines
  1. getline:
  2.  
  3. Syntax:    getline ( "filename" )
  4.  
  5. Description:
  6.  
  7.     Getline returns an N-element list which contains all of the
  8.     tokens from a line in the file described by "filename". The
  9.     tokens are delimited by whitespace. Numbers are installed in
  10.     the list as numeric scalars, everything else is installed as
  11.     scalar strings. 
  12.  
  13.     The list elements have numeric indices, and are numbered from
  14.     1 to N. The 1st element containing the 1st token on the line,
  15.     and the Nth element containing the last token on the line. The
  16.     newline is not returned as a token.
  17.  
  18.     Getline will also recognize everything enclosed within a pair
  19.     of `"' as a string, including escape characters.
  20.  
  21.     Getline will always return a list-object. When an empty-line
  22.     has been read, getline returns an empty list. Getline will
  23.     terminate on an End-Of-File (EOF).
  24.  
  25.     The filename can be a string that specifies a sub-process (see
  26.     `help FILES'), in which case getline() will run the
  27.     sub-process, and read from the process's standard output.
  28.  
  29.     Examples:
  30.  
  31.     To get input interactively:
  32.  
  33.     > printf( "Enter a string and a number: " ); x = getline( "stdin" );
  34.     Enter a string and a number: test-string 1.234e5
  35.     > show(x)
  36.        name:   x     
  37.        class:  list  
  38.            n:  2     
  39.     > x.[1]
  40.     test-string
  41.     > x.[2]
  42.      2 =
  43.      1.23e+05
  44.  
  45.     Given a file named `test', which contains the following lines:
  46.  
  47.     jcool  259  4 1075  822 vt01     S   Dec 29  9:32 X :0 -p 1 -s 5 
  48.     jcool  256  0   21    0 console  S   Dec 29  0:00 startx 
  49.     jcool  261  0  338   88 console  S   Dec 29  0:16 twm 
  50.     jcool  288  8  635  333 ?        S   Dec 29  2:00 emacs 
  51.     jcool  287  0  408   65 console  S   Dec 29  0:01 xclock 
  52.     
  53.     tmp = getline( "test" );
  54.     
  55.     would produce a list variable named `tmp' with 16 elements:
  56.     tmp.[1] would be the string "jcool" and tmp.[16] would be the
  57.     number 5.  The next call to getline() would read the second
  58.     line in the file, and create a new list containing those
  59.     elements.
  60.  
  61.     The above could also have been done with:
  62.  
  63.     tmp = getline( "|ps -aux | grep jcool" )
  64.  
  65.     Which would open a readable pipe to the "ps -aux | grep jcool"
  66.     command and grab a line at a time from the process.
  67.     
  68.     To read the entire contents of a file:
  69.  
  70.     if (length (ans = getline("stdin"))) 
  71.     { 
  72.       // do something with ans
  73.     else
  74.       // finish up
  75.         }
  76.  
  77.     Since getline returns an empty list when there is no input, we
  78.     can tell when to terminate the input loop by checking the
  79.     length of the returned list.
  80.  
  81. See Also: FILES, LIST
  82.